docs/platform-engineer-guide/observability-alerting.mdx (3)

480-487: Clarify the secret name dependency.

The documentation assumes the secret is named observer-secret, but this name is configurable via the observer.secretName Helm value. Consider adding a note to clarify this or reference where users can find their configured secret name.

📝 Suggested clarification

-Update the `ExternalSecret` named `observer-secret` in the `openchoreo-observability-plane` namespace with `ALERT_STORE_DSN`:
+Update the `ExternalSecret` (typically named `observer-secret`, or as configured via `observer.secretName`) in the `openchoreo-observability-plane` namespace to include `ALERT_STORE_DSN`:

Based on context snippet 1 from the Helm reference, which shows that observer.secretName is configurable.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/platform-engineer-guide/observability-alerting.mdx` around lines 480 -
487, Clarify that the example uses a secret named observer-secret but that the
actual secret name is configurable via the Helm value observer.secretName;
update the text around the ExternalSecret example to mention observer.secretName
(and where to find it in the Helm values) and note that if the chart was
installed with a different observer.secretName the ExternalSecret resource
should use that name and not assume observer-secret in the
openchoreo-observability-plane namespace.

---

468-497: Consider adding database setup and troubleshooting guidance.

The PostgreSQL configuration steps are clear, but platform engineers would benefit from additional operational details:

1. Database schema initialization: Does the Observer automatically create tables on first startup, or do users need to run migrations?
2. Error handling: What happens if the ALERT_STORE_DSN is missing or the database is unreachable? Include troubleshooting guidance.
3. Data migration: If switching from SQLite to PostgreSQL on an existing deployment, is there a migration path for existing alert data?
4. Complete Helm upgrade example: Line 497 mentions "Apply the updated values with helm upgrade" but doesn't show the actual command syntax, which could be confusing for less experienced users.

💡 Example additions

After Step 1:

The Observer will automatically initialize the database schema on first startup. Ensure the PostgreSQL user has CREATE TABLE permissions.

After Step 3:

**Step 4: Verify the Observer deployment.**

```bash
kubectl logs -n openchoreo-observability-plane deployment/observer

If the Observer fails to start, check for database connection errors in the logs. Common issues include incorrect DSN format or network connectivity to PostgreSQL.

Replace line 497 with a complete example:
```markdown
Apply the updated values using:

```bash
helm upgrade openchoreo-observability-plane <chart-reference> \
  --namespace openchoreo-observability-plane \
  --values updated-values.yaml

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/platform-engineer-guide/observability-alerting.mdx around lines 468 -
497, Add operational guidance for the Observer related to PostgreSQL: state
whether the Observer auto-initializes the DB schema (or requires migrations) and
note required DB permissions (e.g., CREATE TABLE) in the section around "Step 1"
and reference the Alert store user; document error handling for missing/invalid
ALERT_STORE_DSN or unreachable DB (include how to check logs via kubectl logs -n
openchoreo-observability-plane deployment/observer and common failure modes),
provide migration guidance if switching from SQLite to PostgreSQL (or point to a
migration tool/process) near the "Data migration" note, and replace the vague
"helm upgrade" line with a concrete helm upgrade invocation example that
includes release name, chart reference, namespace, and --values file while
referencing the observer.alertStoreBackend/postgresql setting and the
observer-secret ExternalSecret update.

</details>

---

`474-478`: **Add note about when ALERT_STORE_DSN is required.**

The connection string format is correct, but it would be helpful to explicitly state that `ALERT_STORE_DSN` is only required when using the PostgreSQL backend to avoid confusion.



<details>
<summary>📝 Suggested addition</summary>

```diff
 **Step 2: Add `ALERT_STORE_DSN` to the Observer Secret.**
 
+The `ALERT_STORE_DSN` environment variable is only required when `alertStoreBackend` is set to `postgresql`.
+
 The `ALERT_STORE_DSN` value must be a standard PostgreSQL connection URL:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/platform-engineer-guide/observability-alerting.mdx` around lines 474 -
478, Add a short clarifying sentence after the ALERT_STORE_DSN connection string
that states the ALERT_STORE_DSN environment variable is only required when the
PostgreSQL backend is selected (e.g., when using the PostgreSQL alert store),
and not needed for other backends; reference the variable name ALERT_STORE_DSN
and the PostgreSQL backend in the sentence so readers know when to supply this
connection URL.